VHL.Setup
This command creates a VHL file dynamically and transfers it to the reader's RAM. The VHL file specifies the card-specific memory structure required to call VHL.Read or VHL.Write. You need to run VHL.Setup if you don't want to configure the readers with a static VHL file ( learn more ).
To run VHL.Format, you cannot use a dynamic VHL file. In this case, you have to follow the standard VHL implementation with a static VHL file.
What to specify
To describe the memory structure, provide a list of parameters depending on the card type (see optional fields in the Parameters table below). If you omit a parameter, the reader will use the default value. To fill in the parameter values, please refer to the card specification. For LEGIC or MIFARE cards, you can also analyze the card structure using BALTECH ID-engine Explorer.
Mixing dynamic and static VHL files
In principle, it is possible to mix dynamic VHL files and static VHL files (as part of the reader configuration for the VHL & Autoread ). However, please note that the dynamic VHL file is lost as soon as you run VHL.Read or VHL.Write with a static VHL file. Thus, if you later want to run VHL.Read or VHL.Write with the dynamic VHL file again, you first need to rerun VHL.Setup to recreate the dynamic VHL file.
Properties
- Command code: 0x0107
- Command timeout: 100 ms
- Possible status codes: General status codes, VHL.ErrNoTag, VHL.ErrCardNotSelected, VHL.ErrHf, VHL.ErrConfig, VHL.ErrRead, VHL.ErrHw , VHL.ErrApdu
Parameters (request frame)
| Name | Type/Size | Description | |||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ConsideredCardType | Enumeration (8 bits) |
Type of card to consider. The default value is 0x00, i.e. the reader will use the card type detected by VHL.Select . To handle the card as a different type (e.g. handle a DESFire card as an inter-industry ISO 14443-4 card), set this value to the desired card type. Not all card types support all VHL commands. For details, see our overview of supported commands The type of the selected card. Since there are no reliable identification standards amongst card manufacturers, we use a heuristic that examines the UID, its length, and other information as documented here. Due to the lack of standards, we cannot guarantee the card type is always identified correctly. Values:
|
|||||||||||||||||||||||||||
| RFU | Raw data (length 1 Byte) |
Fixed value 0x00 |
|||||||||||||||||||||||||||
| Optional field, condition: ConsideredCardType == ConsideredCardType.MifareClassic | |||||||||||||||||||||||||||||
| MifareKeyLen | Raw data (length 1 Byte) |
Fixed value 0x06 |
|||||||||||||||||||||||||||
| MifareKey | Raw data (length 6 Bytes) | Encryption key to access the card. | |||||||||||||||||||||||||||
| AsKeyALen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| AsKeyA | Boolean (8 bits) |
If true, Key A is used to access the card.
If false, Key B is used. |
|||||||||||||||||||||||||||
| MadIdLen | Raw data (length 1 Byte) |
Fixed value 0x02 |
|||||||||||||||||||||||||||
| MadId | Integer (16 bits) |
2-byte application ID (AID) that identifies the sectors to access. If specified, only the payload of that application will be accessed. If not specified, the payload of all sectors will be accessed. All sector trailer blocks and block 0 will be omitted, i.e. the following block order is used: 1,2,4,5,6,8, etc. (0,3,7, etc. are omitted). |
|||||||||||||||||||||||||||
| Optional field, condition: ConsideredCardType == ConsideredCardType.MifareDesfire | |||||||||||||||||||||||||||||
| AppIdLen | Raw data (length 1 Byte) |
Fixed value 0x04 |
|||||||||||||||||||||||||||
| AppId | Integer (32 bits) | Application ID, ranging from 0 to 0x00FFFFFF (big-endian) | |||||||||||||||||||||||||||
| DesfireFileDescLen | Raw data (length 1 Byte) |
Fixed value 0x10 |
|||||||||||||||||||||||||||
| DesfireFileDesc.FileNo | Integer (8 bits) |
The DESFire file number to access (Minimum value: 0, maximum value: 31) |
|||||||||||||||||||||||||||
| DesfireFileDesc.FileCommunicationSecurity | Enumeration (8 bits) |
Communication settings that define if data is to be
MAC'ed or encrypted before it's transmitted to the
host system. Values:
|
|||||||||||||||||||||||||||
| DesfireFileDesc.FileType | Enumeration (8 bits) |
Type of file to read
Only Standard and Backup files are supported. There's no support for Cyclic, Record, or Value files. Values:
|
|||||||||||||||||||||||||||
| DesfireFileDesc.ReadKeyNo | Integer (8 bits) |
ReadKeyNo, i.e. the index of the read key within the DESFire application key table The value 14 allows unencrypted access. (Minimum value: 0, maximum value: 14) |
|||||||||||||||||||||||||||
| DesfireFileDesc.WriteKeyNo | Integer (8 bits) |
WriteKeyNo, i.e. the index of the write key within the DESFire application key table The value 14 allows unencrypted access. (Minimum value: 0, maximum value: 14) |
|||||||||||||||||||||||||||
| DesfireFileDesc.Offset | Integer (16 bits) |
Number of the first byte in the DESFire file to map
into the VHL file. (Minimum value: 0, maximum value: 0xFFFF) |
|||||||||||||||||||||||||||
| DesfireFileDesc.Length | Integer (16 bits) |
Length of byte sequence within the DESFire file to
map into the VHL file. (Minimum value: 0, maximum value: 0x7FFF) |
|||||||||||||||||||||||||||
| DesfireFileDesc.ReadKeyIdx | Integer (8 bits) |
Index of the read key on the reader
|
|||||||||||||||||||||||||||
| DesfireFileDesc.WriteKeyIdx | Integer (8 bits) |
Index of the write key on the reader If omitted and WriteKeyNo is equal to ReadKeyNo, it defaults to ReadKeyIdx. Otherwise it defaults to ReadKeyIdx + 1.
|
|||||||||||||||||||||||||||
| DesfireFileDesc.AccessRightsLowByte | Integer (8 bits) |
Only needed to run VHL.Format. This byte is composed of a high nibble ( ReadWriteKeyNo ) and a low nibble ( ChangeKeyNo ). It corresponds to the low byte of the access rights (see DESFire spec 3.5; chapter 8.3) of the DESFire file. The high byte is composed implicitly of ReadKeyNo and WriteKeyNo. |
|||||||||||||||||||||||||||
| DesfireFileDesc.ChangeKeyIdx | Integer (8 bits) |
Only needed to run VHL.Format. Index of the key on the reader that is used to change a key when running VHL.Format. If ChangeKeyNo (see AccessRightsLowByte ) is equal to WriteKeyNo, this value defaults to WriteKeyIdx. Otherwise, it defaults to WriteKeyIdx + 1.
|
|||||||||||||||||||||||||||
| DesfireFileDesc.FileSize | Integer (16 bits) |
Only needed to run VHL.Format. The size of the DESfire file. It's usually Offset + Len. |
|||||||||||||||||||||||||||
| DesfireFileDesc.IsoFid | Integer (16 bits) |
Only needed to run VHL.Format. ISO file identifier (ISO FID). If the card already contains a DESFire file with the same ISO FID, the existing file will be replaced. If this value is not specified (or 0x3F00), no ISO FID will be used. |
|||||||||||||||||||||||||||
| Length of Key | Integer (8 bits) |
Length of Key in bytes |
|||||||||||||||||||||||||||
| Key | Raw data | Key with preceding crypto byte. Please refer to Device / CryptoKey SubKey for more details. | |||||||||||||||||||||||||||
| Optional field, condition: (ConsideredCardType == ConsideredCardType.LEGICPrimeLegacy) or (ConsideredCardType == ConsideredCardType.LEGICAdvantLegacy) or (ConsideredCardType == ConsideredCardType.LEGICPrime) or (ConsideredCardType == ConsideredCardType.LEGICAdvantIso14443a) or (ConsideredCardType == ConsideredCardType.LEGICAdvantIso15693) | |||||||||||||||||||||||||||||
| Length of SegmentInfo | Integer (8 bits) |
Length of SegmentInfo in bytes |
|||||||||||||||||||||||||||
| SegmentInfo | Raw data | Either segment number or stamp, as defined in the EnStamp parameter. By default, the first segment will be accessed using its segment number. | |||||||||||||||||||||||||||
| EnStampLen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| EnStamp | Boolean (8 bits) |
If true, SegmentInfo contains
a stamp, i.e. the identifier of the application.
This parameter will only be evaluated if SegmentInfo has a length of 1. In this case, the reader can't distinguish between ID and stamp as a valid segment number always has length 1. |
|||||||||||||||||||||||||||
| AdrModeLen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| AdrMode | Enumeration (8 bits) |
Specifies the addressing mode. This parameter is only available on readers supporting LEGIC advant. LEGIC prime readers ignore it. To allow for backward compatibility with LEGIC prime readers, omitting this parameter will not result in the default value, but in the following behavior: VHL address 0 is mapped to protocol header address 25, starting with the first data byte after the longest possible LEGIC prime stamp. Values:
|
|||||||||||||||||||||||||||
| Optional field, condition: ConsideredCardType == ConsideredCardType.Iso15693 | |||||||||||||||||||||||||||||
| FirstBlockLen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| FirstBlock | Integer (8 bits) |
First block of the application data
Firmware versions 1100 2.07.00 and above also support a 16-bit length value. This is not explicitly documented. |
|||||||||||||||||||||||||||
| BlockCountLen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| BlockCount | Integer (8 bits) |
Number of blocks occupied by the application data
Firmware versions 1100 2.07.00 and above also support a 16-bit length value. This is not explicitly documented. |
|||||||||||||||||||||||||||
| OptionFlagLen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| OptionFlag | Enumeration (8 bits) |
Option flag value for read/write operations Values:
|
|||||||||||||||||||||||||||
| BlockSizeLen | Raw data (length 1 Byte) |
Fixed value 0x01 |
|||||||||||||||||||||||||||
| BlockSize | Integer (8 bits) | Block size in bytes | |||||||||||||||||||||||||||
| Optional field, condition: (ConsideredCardType == ConsideredCardType.Iso14443aInterIndustry) or (ConsideredCardType == ConsideredCardType.Iso14443aIntIndustryMif) | |||||||||||||||||||||||||||||
| SelectFileCmdListLen | Integer (8 bits) | Length of SelectFileCmdList (including the following "Length of SelectFileCmdList" field) in bytes | |||||||||||||||||||||||||||
| Length of SelectFileCmdList | Integer (8 bits) |
Number of elements in the SelectFileCmdList array
|
|||||||||||||||||||||||||||
| SelectFileCmdList | Array | - | |||||||||||||||||||||||||||
| FileSpecifier | Enumeration (8 bits) |
The method to select the file Values:
|
|||||||||||||||||||||||||||
| Optional field, condition: FileSpecifier == FileSpecifier.SelectByName | |||||||||||||||||||||||||||||
| Length of Name | Integer (8 bits) |
Length of Name in bytes |
|||||||||||||||||||||||||||
| Name | Raw data | The name of the DF to be selected (1..16 bytes) | |||||||||||||||||||||||||||
| Optional field, condition: FileSpecifier == FileSpecifier.SelectByPath | |||||||||||||||||||||||||||||
| Length of Path | Integer (8 bits) |
Length of Path in bytes |
|||||||||||||||||||||||||||
| Path | Raw data | A list of one or more 16-bit file IDs | |||||||||||||||||||||||||||
| Optional field, condition: FileSpecifier == FileSpecifier.SelectByAPDU | |||||||||||||||||||||||||||||
| Length of ApduCommand | Integer (8 bits) |
Length of ApduCommand in bytes |
|||||||||||||||||||||||||||
| ApduCommand | Raw data | APDU command by which to select the file | |||||||||||||||||||||||||||
| FileLenLength | Raw data (length 1 Byte) |
Fixed value 0x04 |
|||||||||||||||||||||||||||
| FileLen | Integer (32 bits) | File length in bytes | |||||||||||||||||||||||||||
| ApduTimeoutLength | Raw data (length 1 Byte) |
Fixed value 0x02 |
|||||||||||||||||||||||||||
| ApduTimeout | Integer (16 bits) |
Timeout for APDU command execution in ms. The default value is 2500 ms. Keep in mind that this timeout may add up several times in the scope of a single read or write access as file selection usually requires multiple APDUs to be executed. |
|||||||||||||||||||||||||||
Returned values (response frame)
None